home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 2004 #2 / Amiga Plus CD - 2004 - No. 02.iso / AmiSoft / Dev / misc / WHDLoad_dev.lha / WHDLoad / Src / sources / whdload / kick.readme < prev    next >
Encoding:
Text File  |  2003-07-16  |  10.0 KB  |  302 lines
  1.  
  2. $Id: kick.readme 1.12 2003/07/15 20:38:31 wepl Exp $
  3.  
  4. Symbols in the Slave-Source
  5. ***************************
  6.  
  7. There are two classes of Symbols to define in the Slave-Source. The first
  8. class must be specified to setup essential informations for the system. The
  9. second class contains optional Symbols changing some behaviors of the
  10. emulation.
  11.  
  12. Additional there are required flags in the ws_Flags field of the WHDLoadSlave
  13. structure. The flag WHDLF_EmulPriv must be always set because the exec
  14. function Supervisor requires it to change from user-mode into supervisor-mode.
  15. The flag WHDLF_Examine is only required if the file system handler (see
  16. HDINIT) is used.
  17.  
  18.  
  19. Required Symbols
  20. ----------------
  21.  
  22. CHIPMEMSIZE = $80000
  23.  
  24. That specfies the amount of Chip-Memory for the system. Allowed values are
  25. between $1000 and $200000. It is recommended to start with a full value like
  26. $80000 or $100000, and later to adjust that value to the minimum required
  27. using the MEMFREE feature (see below).
  28.  
  29. FASTMEMSIZE = $10000
  30.  
  31. That specifies the Fast-Memory (better to say ExpMem because it can be ChipMem
  32. too if not enough FastMem is available) for the system. Allowed values are
  33. 0 upto any what WHDLoad supports.
  34.  
  35. NUMDRIVES = 1
  36.  
  37. That sets the number of drives which will get detected by the emulated system.
  38. The amount has nothing to do with the amount of physically available drives!
  39. Allowed values are -1 ... 4. The value -1 has special meaning that Custom1/N
  40. is used to set drive count. If Custom1/N is not specified (its zero) than one
  41. drive will be used. Setting the drivecount to 0 works only with Kickstart 3.1,
  42. the older Kickstarts 1.2 and 1.3 will crash if there is no floppy drive.
  43.  
  44. WPDRIVES = %0000
  45.  
  46. That sets the protections state for the emulated floppy drives. Bit #0 means
  47. drive DF0: and the bitvalue 0 means 'write protected' and 1 means
  48. 'read/write'. E.g. %1111 means all drives 'read/write'.
  49.  
  50.  
  51. Optional Symbols
  52. ----------------
  53.  
  54. BLACKSCREEN
  55.  
  56. That symbol forces all colors (0-4,17-19) in the default system (intuition)
  57. preferences to null. The result is that the initial AmigaDOS boot screen will
  58. be invisible.
  59.  
  60. CACHE
  61.  
  62. The presence of that symbol enables full cpu caches for the expansion memory
  63. before the kickstart is booting. That gives best performance for the installed
  64. program. Chip memory remains uncached.
  65.  
  66. DEBUG
  67.  
  68. If that symbol is defined various checks will be included in the emulation
  69. code. It should be enabled during the development task and removed for final
  70. releases.
  71.  
  72. DISKSONBOOT
  73.  
  74. If that symbol is defined there will be disks inserted in the drives at
  75. booting time. Otherwise all drives will be empty. If the symbol is set, DF0:
  76. will contain 'Disk.1', DF1: 'Disk.2' an so on. To insert or change disks in
  77. the drives use the function _trd_changedisk (see below).
  78.  
  79. DOSASSIGN
  80.  
  81. If that symbol is defined the subroutine _dos_assign will be included and can
  82. be used (see below).
  83.  
  84. FONTHEIGHT
  85.  
  86. If defined that symbol sets the system default font height in the preferences
  87. (intuition), under Kick1.3 the default is 9 (60 chars per line), 8 makes 80
  88. chars per line on a standard screen.
  89.  
  90. HDINIT
  91.  
  92. If that symbol is defined a dos filesystem handler will be installed which
  93. mounts the actual directory as a drive called DH0: (volume has name
  94. 'WHDLoad'). If there is no bootable disk inserted (check DISKSONBOOT) the
  95. dos.library will try to boot from that device. HDINIT requires that the flag
  96. WHDLF_Examine to be set!
  97.  
  98. HRTMON
  99.  
  100. The presence of that symbol adds some debugging support for HrtMon. HrtMon
  101. reads to much from the stackframe if entered. If the SSP is at the end of the
  102. memory that will cause an access fault. The symbol results in a decremented
  103. SSP.
  104.  
  105. IOCACHE = 1024
  106.  
  107. If the symbol is defined it enables a read/write cache in conjuction with
  108. option HDINIT. The cache will be allocated on request for each opened file
  109. seperately. If the installed program uses savegames you should probably set
  110. the IOCACHE to the size of the savegame (or at least half/quarter) to minimize
  111. the amount OS swaps. If you use large values you maybe need to increase the
  112. memory for the installed program.
  113.  
  114. INITAGA
  115.  
  116. Only available in kick31.s. Enables the AGA graphics modes using
  117. gfx.SetChipRev(SETCHIPREV_BEST).
  118.  
  119. INIT_AUDIO
  120.  
  121. Only available in kick31.s. Forces the kickstart to initialize the
  122. audio.device.
  123.  
  124. INIT_GADTOOLS
  125.  
  126. Only available in kick31.s. Forces the kickstart to initialize the
  127. gadtools.library.
  128.  
  129. INIT_MATHFFP
  130.  
  131. Only available in kick31.s. Forces the kickstart to initialize the
  132. mathffp.library.
  133.  
  134. MEMFREE = $100
  135.  
  136. If this symbol is defined the function exec.AllocMem will be patched. At each
  137. call to this function the size of the largest free memory chunk will be
  138. calculated and saved at the specified address if lower than the previous one.
  139. Using this feature it is absolutely simple to optimize the memory requirements
  140. and avoid memory wasting. Test a game trough all paths with that symbol
  141. defined. Then make a dump and checkout the memory dump file. At address
  142. (MEMFREE) you will find the lowest free chip memory during the games lifetime.
  143. At address (MEMFREE+4) you will find the same for fast memory.
  144. The MEMFREE has also the side effect that trashing the memory list will be
  145. detected on the next AllocMem call because AvailMem(LARGEST) used in MEMFREE
  146. will traverse all free memory. This may be useful for debugging.
  147.  
  148. NEEDFPU
  149.  
  150. If that symbol is defined the system will get informed if an FPU is preset
  151. (execbase.AttnFlags). If the symbol is not defined the system will think there
  152. is no FPU regardless if there is one really. The system will use a different
  153. task switching routine which will save also the FPU registers if a FPU is
  154. present.
  155.  
  156. POINTERTICKS
  157.  
  158. If defined that symbol sets the system default mouse speed in the preferences
  159. (intuition). The system default is 2. Setting 1 means fast, 4 slow.
  160.  
  161. SETPATCH
  162.  
  163. If that symbol is defined nearly all patches done by the SetPatch v1.38
  164. program will be performed. Usually that is not necessary and omitting the
  165. option makes the Slave around 400 bytes shorter. Only available in kick12.s
  166. and kick13.s.
  167.  
  168. STACKSIZE
  169.  
  170. Using this symbol the default stacksize can be set. The initial CLI structure
  171. will be patched for this. The system default on V33 and V34 is 4000 bytes, on
  172. V40 it's 4096 bytes.
  173.  
  174. TRDCHANGEDISK
  175.  
  176. If that symbol is defined the subroutine _trd_changedisk will be included and
  177. can be used (see below).
  178.  
  179.  
  180. Labels in the Slave-Source
  181. **************************
  182.  
  183. In the old style Slaves it was sufficient to only define the labels below.
  184. Beginning with the new style and WHDLoad v16 the kicknn.s will be included at
  185. the top of the slave source which results in that these labels are not visible
  186. to kicknn.s in the first assembling pass. This can cause problems with your
  187. assembler (e.g. "Internal Global Optimize Error" with BASM). To aid this you
  188. must define an uppercase symbol without the underlines (e.g. BOOTEARLY for
  189. _bootearly) before including kicknn.s in your slave source (see examples).
  190.  
  191. _bootearly
  192.  
  193.     * will be entered before any diskaccess are performed by the Kickstart
  194.     * NO dos.library exists at this time!
  195.     * you can continue the boot process by returning via a RTS
  196.  
  197. _bootblock
  198.  
  199.     * will be entered after the bootblock has been loaded from the disk in
  200.       drive DF0:, that is the point at which Kickstart normally jumps into
  201.       bootblock
  202.     * Registers upon calling:
  203.       A1 = ioreq, initialized to access trackdisk.device unit 0
  204.       A0/A4 = buffer, containing the already loaded bootblock (1024 bytes)
  205.         on Kick 1.2/1.3 its A4 on Kick 3.1 its A0
  206.       A6 = execbase
  207.     * NO dos.library exists at this time!
  208.     * you can continue the boot process by returning via a RTS
  209.  
  210. _bootdos
  211.  
  212.     * that label will called like a program located in the startup-
  213.       sequence, that means it is a real CLI process, input and output
  214.       streams are connected to the initial CLI window
  215.     * dos.library is fully initialized and usable
  216.     * the routine behind the label may return via a RTS, then the control
  217.       is returned to the dos.library and the prompt will appear in the
  218.       initial CLI window
  219.     * _bootdos requires option HDINIT, because it uses a virtual
  220.       startup-sequence and a virtual program loaded from within
  221.  
  222. _cb_dosLoadSeg
  223.  
  224.     * that label will be called after each successful execution of
  225.       dos.LoadSeg and can be used to patch the loaded programs
  226.     * Registers upon calling:
  227.       D0 = BSTR name of the loaded program as BCPL string
  228.       D1 = BPTR segment list of the loaded program as BCPL pointer
  229.     * the routine may destroy all registers but must return via RTS
  230.  
  231. _cb_dosRead
  232.  
  233.     * works only in conjunction with HDINIT
  234.     * that label will be called after each successful execution of
  235.       dos.Read and can be used to patch the loaded data
  236.     * Registers upon calling:
  237.       D0 = ULONG amount of bytes read during current Read
  238.       D1 = ULONG offset in file on start of current Read
  239.       A0 = CPTR  full name of file
  240.       A1 = APTR  buffer to the data has been read
  241.     * the routine may destroy all registers but must return via RTS
  242.  
  243. Functions in kick(12|13|31).s
  244. *****************************
  245.  
  246. _dos_assign
  247.     * only avaliable if DOSASSIGN is defined
  248.     * performs a C:Assign like operation
  249.     * SYNOPSIS
  250.         IN:    A0 = CPTR destination name
  251.             A1 = CPTR directory (can be 0 meaning SYS:)
  252.         OUT:    -
  253.     * only under kick12/13.s you may also assign device names to a
  254.       directory!
  255.     * EXAMPLE
  256.         lea    (_name,pc),a0
  257.         sub.l    a1,a1
  258.         bsr    _dos_assign
  259.         ...
  260.       _name dc.b    "DataDisk",0
  261.  
  262. _trd_changedisk
  263.     * only avaliable if TRDCHANGEDISK is defined
  264.     * change a disk in a trackdisk.device unit
  265.     * SYNOPSIS
  266.         IN:    D0 = BYTE unit
  267.             D1 = BYTE number of disk image to insert
  268.         OUT:    -
  269.     * will cause two diskchanges as usual, one for removing the old disk
  270.       and one for inserting the new one
  271.  
  272. _flushcache
  273.     * flush cpu caches
  274.     * all registers will preserved
  275.  
  276.  
  277. Labels in kick(12|13|31).s
  278. **************************
  279.  
  280. _attnflags
  281.     * a long word containing the exec.AttnFlags
  282.     * EXAMPLE
  283.         move.l    (_attnflags,pc),d0
  284.         btst    #AFB_68020,d0
  285.         beq    ...
  286.  
  287. _dosname
  288.     * only avaliable if HDINIT is defined
  289.     * containing "dos.library"
  290.     * maybe used to open dos.library
  291.  
  292. _monitor
  293.     * a long word containing the actual monitor
  294.     * EXAMPLE
  295.         move.l    (_monitor,pc),d0
  296.         cmp.l    #PAL_MONITOR_ID,d0
  297.         beq    ...
  298.  
  299. _resload
  300.     * containing resload base
  301.  
  302.